<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">

<title>signals - RDoc Documentation</title>


<script src="./js/navigation.js" defer></script>
<script src="./js/search.js" defer></script>
<script src="./js/search_index.js" defer></script>
<script src="./js/searcher.js" defer></script>
<script src="./js/darkfish.js" defer></script>

<script src="./js/jquery-3.2.0.min.js"></script>

<script src="./js/vue.min.js"></script>
<script src="./js/js.cookie.min.js"></script>

<link href="./css/fonts.css" rel="stylesheet">
<link id='rdoccss' href="./css/rdoc.css" rel="stylesheet">
<link href="./css/carbon17.css" rel="stylesheet">

<script type="text/javascript">
  var rdoc_rel_prefix = "./";
  var index_rel_prefix = "./";
  var darkModeCsseHref = "./css/rdoc-dm.css"
  var defaultModeCssHref = "./css/rdoc.css"
  // var cssDarkmode = Cookies.get('darkmode');
  
  if( Cookies.get("darkmode") == "true") {
	$('#rdoccss').attr("href", darkModeCsseHref);
}

//  https://cssdeck.com/blog/simple-jquery-stylesheet-switcher/

document.write('<style type="text/css">body{display:none}</style>');

</script>


</head>
<body id="top" role="document" class="file">
  <!-- this is page.html -->
  <div id='actionbar' >
    <div class='wrapper mdiv'>
      <ul class='grids g0'></ul>
    </div> 
    <!-- VERSION HEADER for 3.3.0-preview2 NOT FOUND -->
  </div> <!-- end action bar -->


 <div class='wrapper hdiv'>

 


<nav id='vapp' role="navigation">
  <div id="project-navigation">
    <div id="home-section" role="region" title="Quick navigation" class="nav-section">
  <h2><a href="./index.html" rel="home">Home</a></h2>

  <div id="table-of-contents-navigation"  >
    <a href="./table_of_contents.html#pages">Pages</a>
    <a href="./table_of_contents.html#classes">Classes</a>
    <a href="./table_of_contents.html#methods">Methods</a>
  </div>
</div>

    <div id="search-section" role="search" class="project-section initially-hidden">
  <form action="#" method="get" accept-charset="utf-8">
    <div id="search-field-wrapper">
      <input id="search-field" role="combobox" aria-label="Search"
             aria-autocomplete="list" aria-controls="search-results"
             type="text" name="search" placeholder="Search" spellcheck="false"
             title="Type to search, Up and Down to navigate, Enter to load">
    </div>

    <ul id="search-results" aria-label="Search Results"
        aria-busy="false" aria-expanded="false"
        aria-atomic="false" class="initially-hidden"></ul>
  </form>
</div>

  </div>

  
<div class="nav-section">
  <h3>Table of Contents</h3>

  <ul class="link-list" role="directory">
    <li><a href="#label-Caveats+for+implementing+Signal.trap+callbacks">Caveats for implementing Signal.trap callbacks</a>
    <li><a href="#label-An+implementation+detail+of+the+Ruby+VM">An implementation detail of the Ruby VM</a>
    <li><a href="#label-Unsafe+methods+to+call+in+Signal.trap+blocks">Unsafe methods to call in Signal.trap blocks</a>
    <li><a href="#label-Commonly+safe+operations+inside+Signal.trap+blocks">Commonly safe operations inside Signal.trap blocks</a>
    <li><a href="#label-System+call+wrapper+methods+which+are+safe+inside+Signal.trap">System call wrapper methods which are safe inside Signal.trap</a>
  </ul>
</div>

  <button id='toggleThing' @click="toggleNav()" >Show/hide navigation</button>

  <div id="project-metadata">
   <div :class="isOpen ? 'block' : 'hidden' " id='toggleMe'>
    
<div id="fileindex-section" class="nav-section">
  <h3>Pages</h3>

  <ul class="link-list">
    <li><a href="./NEWS/NEWS-1_8_7.html">NEWS-1.8.7</a>
    <li><a href="./NEWS/NEWS-1_9_1.html">NEWS-1.9.1</a>
    <li><a href="./NEWS/NEWS-1_9_2.html">NEWS-1.9.2</a>
    <li><a href="./NEWS/NEWS-1_9_3.html">NEWS-1.9.3</a>
    <li><a href="./NEWS/NEWS-2_0_0.html">NEWS-2.0.0</a>
    <li><a href="./NEWS/NEWS-2_1_0.html">NEWS-2.1.0</a>
    <li><a href="./NEWS/NEWS-2_2_0.html">NEWS-2.2.0</a>
    <li><a href="./NEWS/NEWS-2_3_0.html">NEWS-2.3.0</a>
    <li><a href="./NEWS/NEWS-2_4_0.html">NEWS-2.4.0</a>
    <li><a href="./NEWS/NEWS-2_5_0.html">NEWS-2.5.0</a>
    <li><a href="./NEWS/NEWS-2_6_0.html">NEWS-2.6.0</a>
    <li><a href="./NEWS/NEWS-2_7_0.html">NEWS-2.7.0</a>
    <li><a href="./NEWS/NEWS-3_0_0_md.html">NEWS-3.0.0</a>
    <li><a href="./NEWS/NEWS-3_1_0_md.html">NEWS-3.1.0</a>
    <li><a href="./NEWS/NEWS-3_2_0_md.html">NEWS-3.2.0</a>
    <li><a href="./bsearch_rdoc.html">bsearch</a>
    <li><a href="./bug_triaging_rdoc.html">bug_triaging</a>
    <li><a href="./case_mapping_rdoc.html">case_mapping</a>
    <li><a href="./character_selectors_rdoc.html">character_selectors</a>
    <li><a href="./command_injection_rdoc.html">command_injection</a>
    <li><a href="./contributing_md.html">contributing</a>
    <li><a href="./contributing/building_ruby_md.html">building_ruby</a>
    <li><a href="./contributing/documentation_guide_md.html">documentation_guide</a>
    <li><a href="./contributing/glossary_md.html">glossary</a>
    <li><a href="./contributing/making_changes_to_ruby_md.html">making_changes_to_ruby</a>
    <li><a href="./contributing/making_changes_to_stdlibs_md.html">making_changes_to_stdlibs</a>
    <li><a href="./contributing/reporting_issues_md.html">reporting_issues</a>
    <li><a href="./contributing/testing_ruby_md.html">testing_ruby</a>
    <li><a href="./dig_methods_rdoc.html">dig_methods</a>
    <li><a href="./distribution_md.html">distribution</a>
    <li><a href="./dtrace_probes_rdoc.html">dtrace_probes</a>
    <li><a href="./encodings_rdoc.html">encodings</a>
    <li><a href="./extension_ja_rdoc.html">extension.ja</a>
    <li><a href="./extension_rdoc.html">extension</a>
    <li><a href="./fiber_md.html">fiber</a>
    <li><a href="./format_specifications_rdoc.html">format_specifications</a>
    <li><a href="./globals_rdoc.html">globals</a>
    <li><a href="./implicit_conversion_rdoc.html">implicit_conversion</a>
    <li><a href="./keywords_rdoc.html">keywords</a>
    <li><a href="./maintainers_md.html">maintainers</a>
    <li><a href="./marshal_rdoc.html">marshal</a>
    <li><a href="./memory_view_md.html">memory_view</a>
    <li><a href="./optparse/argument_converters_rdoc.html">argument_converters</a>
    <li><a href="./optparse/creates_option_rdoc.html">creates_option</a>
    <li><a href="./optparse/option_params_rdoc.html">option_params</a>
    <li><a href="./optparse/tutorial_rdoc.html">tutorial</a>
    <li><a href="./packed_data_rdoc.html">packed_data</a>
    <li><a href="./ractor_md.html">ractor</a>
    <li><a href="./regexp_rdoc.html">regexp</a>
    <li><a href="./regexp/methods_rdoc.html">methods</a>
    <li><a href="./regexp/unicode_properties_rdoc.html">unicode_properties</a>
    <li><a href="./ruby_3_3_0_preview2/COPYING.html">COPYING</a>
    <li><a href="./ruby_3_3_0_preview2/COPYING_ja.html">COPYING.ja</a>
    <li><a href="./ruby_3_3_0_preview2/LEGAL.html">LEGAL</a>
    <li><a href="./ruby_3_3_0_preview2/NEWS_md.html">NEWS</a>
    <li><a href="./ruby_3_3_0_preview2/README_ja_md.html">README.ja</a>
    <li><a href="./ruby_3_3_0_preview2/README_md.html">README</a>
    <li><a href="./security_rdoc.html">security</a>
    <li><a href="./signals_rdoc.html">signals</a>
    <li><a href="./standard_library_rdoc.html">standard_library</a>
    <li><a href="./strftime_formatting_rdoc.html">strftime_formatting</a>
    <li><a href="./syntax_rdoc.html">syntax</a>
    <li><a href="./syntax/assignment_rdoc.html">assignment</a>
    <li><a href="./syntax/calling_methods_rdoc.html">calling_methods</a>
    <li><a href="./syntax/comments_rdoc.html">comments</a>
    <li><a href="./syntax/control_expressions_rdoc.html">control_expressions</a>
    <li><a href="./syntax/exceptions_rdoc.html">exceptions</a>
    <li><a href="./syntax/literals_rdoc.html">literals</a>
    <li><a href="./syntax/methods_rdoc.html">methods</a>
    <li><a href="./syntax/miscellaneous_rdoc.html">miscellaneous</a>
    <li><a href="./syntax/modules_and_classes_rdoc.html">modules_and_classes</a>
    <li><a href="./syntax/pattern_matching_rdoc.html">pattern_matching</a>
    <li><a href="./syntax/precedence_rdoc.html">precedence</a>
    <li><a href="./syntax/refinements_rdoc.html">refinements</a>
    <li><a href="./timezones_rdoc.html">timezones</a>
    <li><a href="./windows_md.html">windows</a>
    <li><a href="./yjit/yjit_md.html">yjit</a>
    <li><a href="./yjit/yjit_hacking_md.html">yjit_hacking</a>
  </ul>
</div>

   </div>
  </div>
</nav>


<!--  carbon ads here -->

<div id='extraz'>
  <div class='adzbox-index'  >
   
  </div>
 </div>         


<main role="main" aria-label="Page signals.rdoc">

<h1 id="label-Caveats+for+implementing+Signal.trap+callbacks">Caveats for implementing <a href="Signal.html#method-c-trap"><code>Signal.trap</code></a> callbacks<span><a href="#label-Caveats+for+implementing+Signal.trap+callbacks">&para;</a> <a href="#top">&uarr;</a></span></h1>

<p>As with implementing signal handlers in C or most other languages, all code passed to <a href="Signal.html#method-c-trap"><code>Signal.trap</code></a> must be reentrant.  If you are not familiar with reentrancy, you need to read up on it at <a href="https://en.wikipedia.org/wiki/Reentrancy_(computing)">Wikipedia</a> or elsewhere before reading the rest of this document.</p>

<p>Most importantly, “thread-safety” does not guarantee reentrancy; and methods such as Mutex#lock and Mutex#synchronize which are commonly used for thread-safety even prevent reentrancy.</p>

<h2 id="label-An+implementation+detail+of+the+Ruby+VM">An implementation detail of the Ruby VM<span><a href="#label-An+implementation+detail+of+the+Ruby+VM">&para;</a> <a href="#top">&uarr;</a></span></h2>

<p>The Ruby VM defers <a href="Signal.html#method-c-trap"><code>Signal.trap</code></a> callbacks from running until it is safe for its internal data structures, but it does not know when it is safe for data structures in YOUR code.  Ruby implements deferred signal handling by registering short C functions with only <a href="http://man7.org/linux/man-pages/man7/signal-safety.7.html">async-signal-safe functions</a> as signal handlers.  These short C functions only do enough tell the VM to run callbacks registered via <a href="Signal.html#method-c-trap"><code>Signal.trap</code></a> later in the main Ruby <a href="Thread.html"><code>Thread</code></a>.</p>

<h2 id="label-Unsafe+methods+to+call+in+Signal.trap+blocks">Unsafe methods to call in <a href="Signal.html#method-c-trap"><code>Signal.trap</code></a> blocks<span><a href="#label-Unsafe+methods+to+call+in+Signal.trap+blocks">&para;</a> <a href="#top">&uarr;</a></span></h2>

<p>When in doubt, consider anything not listed as safe below as being unsafe.</p>
<ul><li>
<p>Mutex#lock, Mutex#synchronize and any code using them are explicitly unsafe.  This includes Monitor in the standard library which uses Mutex to provide reentrancy.</p>
</li><li>
<p><a href="Dir.html#method-c-chdir"><code>Dir.chdir</code></a> with block</p>
</li><li>
<p>any <a href="IO.html"><code>IO</code></a> write operations when <a href="IO.html#method-i-sync"><code>IO#sync</code></a> is false; including <a href="IO.html#method-i-write"><code>IO#write</code></a>, <a href="IO.html#method-i-write_nonblock"><code>IO#write_nonblock</code></a>, <a href="IO.html#method-i-puts"><code>IO#puts</code></a>. Pipes and sockets default to ‘IO#sync = true’, so it is safe to write to them unless <a href="IO.html#method-i-sync"><code>IO#sync</code></a> was disabled.</p>
</li><li>
<p><a href="File.html#method-i-flock"><code>File#flock</code></a>, as the underlying flock(2) call is not specified by POSIX</p>
</li></ul>

<h2 id="label-Commonly+safe+operations+inside+Signal.trap+blocks">Commonly safe operations inside <a href="Signal.html#method-c-trap"><code>Signal.trap</code></a> blocks<span><a href="#label-Commonly+safe+operations+inside+Signal.trap+blocks">&para;</a> <a href="#top">&uarr;</a></span></h2>
<ul><li>
<p>Assignment and retrieval of local, instance, and class variables</p>
</li><li>
<p>Most object allocations and initializations of common types including <a href="Array.html"><code>Array</code></a>, <a href="Hash.html"><code>Hash</code></a>, <a href="String.html"><code>String</code></a>, <a href="Struct.html"><code>Struct</code></a>, <a href="Time.html"><code>Time</code></a>.</p>
</li><li>
<p>Common <a href="Array.html"><code>Array</code></a>, <a href="Hash.html"><code>Hash</code></a>, <a href="String.html"><code>String</code></a>, <a href="Struct.html"><code>Struct</code></a> operations which do not execute a block are generally safe; but beware if iteration is occurring elsewhere.</p>
</li><li>
<p><a href="Hash.html#method-i-5B-5D"><code>Hash#[]</code></a>, <a href="Hash.html#method-i-5B-5D-3D"><code>Hash#[]=</code></a> (unless <a href="Hash.html#method-c-new"><code>Hash.new</code></a> was given an unsafe block)</p>
</li><li>
<p><a href="Thread/Queue.html#method-i-push"><code>Thread::Queue#push</code></a> and <a href="Thread/SizedQueue.html#method-i-push"><code>Thread::SizedQueue#push</code></a> (since Ruby 2.1)</p>
</li><li>
<p>Creating a new <a href="Thread.html"><code>Thread</code></a> via <a href="Thread.html#method-c-new"><code>Thread.new</code></a>/Thread.start can used to get around the unusability of Mutexes inside a signal handler</p>
</li><li>
<p><a href="Signal.html#method-c-trap"><code>Signal.trap</code></a> is safe to use inside blocks passed to <a href="Signal.html#method-c-trap"><code>Signal.trap</code></a></p>
</li><li>
<p>arithmetic on <a href="Integer.html"><code>Integer</code></a> and <a href="Float.html"><code>Float</code></a> (‘+’, ‘-’, ‘%’, ‘*’, ‘/’)</p>

<p>Additionally, signal handlers do not run between two successive local variable accesses, so shortcuts such as ‘+=’ and ‘-=’ will not trigger a data race when used on <a href="Integer.html"><code>Integer</code></a> and <a href="Float.html"><code>Float</code></a> classes in signal handlers.</p>
</li></ul>

<h2 id="label-System+call+wrapper+methods+which+are+safe+inside+Signal.trap">System call wrapper methods which are safe inside <a href="Signal.html#method-c-trap"><code>Signal.trap</code></a><span><a href="#label-System+call+wrapper+methods+which+are+safe+inside+Signal.trap">&para;</a> <a href="#top">&uarr;</a></span></h2>

<p>Since Ruby has wrappers around many <a href="http://man7.org/linux/man-pages/man7/signal-safety.7.html">async-signal-safe C functions</a> the corresponding wrappers for many <a href="IO.html"><code>IO</code></a>, <a href="File.html"><code>File</code></a>, <a href="Dir.html"><code>Dir</code></a>, and Socket methods are safe.</p>

<p>(Incomplete list)</p>
<ul><li>
<p><a href="Dir.html#method-c-chdir"><code>Dir.chdir</code></a> (without block arg)</p>
</li><li>
<p><a href="Dir.html#method-c-mkdir"><code>Dir.mkdir</code></a></p>
</li><li>
<p><a href="Dir.html#method-c-open"><code>Dir.open</code></a></p>
</li><li>
<p><a href="File.html#method-i-truncate"><code>File#truncate</code></a></p>
</li><li>
<p><a href="File.html#method-c-link"><code>File.link</code></a></p>
</li><li>
<p><a href="File.html#method-c-open"><code>File.open</code></a></p>
</li><li>
<p><a href="File.html#method-c-readlink"><code>File.readlink</code></a></p>
</li><li>
<p><a href="File.html#method-c-rename"><code>File.rename</code></a></p>
</li><li>
<p><a href="File.html#method-c-stat"><code>File.stat</code></a></p>
</li><li>
<p><a href="File.html#method-c-symlink"><code>File.symlink</code></a></p>
</li><li>
<p><a href="File.html#method-c-truncate"><code>File.truncate</code></a></p>
</li><li>
<p><a href="File.html#method-c-unlink"><code>File.unlink</code></a></p>
</li><li>
<p><a href="File.html#method-c-utime"><code>File.utime</code></a></p>
</li><li>
<p><a href="IO.html#method-i-close"><code>IO#close</code></a></p>
</li><li>
<p><a href="Object.html#method-i-dup"><code>IO#dup</code></a></p>
</li><li>
<p><a href="IO.html#method-i-fsync"><code>IO#fsync</code></a></p>
</li><li>
<p><a href="IO.html#method-i-read"><code>IO#read</code></a></p>
</li><li>
<p><a href="IO.html#method-i-read_nonblock"><code>IO#read_nonblock</code></a></p>
</li><li>
<p><a href="IO.html#method-i-stat"><code>IO#stat</code></a></p>
</li><li>
<p><a href="IO.html#method-i-sysread"><code>IO#sysread</code></a></p>
</li><li>
<p><a href="IO.html#method-i-syswrite"><code>IO#syswrite</code></a></p>
</li><li>
<p><a href="IO.html#method-c-select"><code>IO.select</code></a></p>
</li><li>
<p><a href="IO.html#method-c-pipe"><code>IO.pipe</code></a></p>
</li><li>
<p><a href="Process.html#method-c-clock_gettime"><code>Process.clock_gettime</code></a></p>
</li><li>
<p><a href="Process.html#method-c-exit-21"><code>Process.exit!</code></a></p>
</li><li>
<p><a href="Process.html#method-c-fork"><code>Process.fork</code></a></p>
</li><li>
<p><a href="Process.html#method-c-kill"><code>Process.kill</code></a></p>
</li><li>
<p><a href="Process.html#method-c-pid"><code>Process.pid</code></a></p>
</li><li>
<p><a href="Process.html#method-c-ppid"><code>Process.ppid</code></a></p>
</li><li>
<p><a href="Process.html#method-c-waitpid"><code>Process.waitpid</code></a></p>
</li></ul>

<p>…</p>

</main>

</div>  <!--  class='wrapper hdiv' -->


<footer id="validator-badges" role="contentinfo">
<p><a href="https://validator.w3.org/check/referer">Validate</a></p>
<p>Generated by <a href="https://ruby.github.io/rdoc/">RDoc</a> 6.4.0.</p>
<p>Based on <a href="https://github.com/ged/darkfish/">Darkfish</a> by <a href="http://deveiate.org">Michael Granger</a>.</p>

  
    <p><p><a href="https://ruby-doc.org">Ruby-doc.org</a> is a service of <a href="https://jamesbritt.com">James Britt</a> and <a href="https://neurogami.com">Neurogami</a>, purveyors of fine <a href='https://jamesbritt.bandcamp.com/'>dance noise</a></p>
</p>
  
  </footer>

<script type="text/javascript">


  let ads  = $("#carbonads-container").children().detach();


  function swapMode() {
    var cookieName = 'darkmode';
    var cssDarkmode = Cookies.get(cookieName);
    console.log("***** swapMode! " + cssDarkmode + " *****");


    if (cssDarkmode == "true") {
      console.log("We have dark mode, set the css to light ...");
      $('#rdoccss').attr("href", defaultModeCssHref);
      $('#cssSelect').text("Dark mode");
      cssDarkmode = "false";
      console.log("swapMode! Now set cookie to " + cssDarkmode);
      Cookies.set(cookieName, cssDarkmode);

    } else {
      console.log("We not have dark mode, set the css to dark ...");
      $('#rdoccss').attr("href", darkModeCsseHref);
      $('#cssSelect').text("Light mode");
      cssDarkmode = "true";
      console.log("swapMode! Now set cookie to " + cssDarkmode);
      Cookies.set(cookieName, cssDarkmode);

    }

    console.log("  --------------- ");
  }


const vueCssApp = new Vue({
el: '#menubar',
data: {
isDark: false
},
methods: {
toggleClass: function(event){
this.isDark = !this.isDark;
}
}
})

const vueApp = new Vue({
el: '#vapp',
data: { 
isOpen: true
},

mounted() {
this.handleResize();
this.manage_mob_classes();
window.addEventListener('resize', this.handleResize)
//this.isOpen !=  (/Android|webOS|iPhone|iPad|iPod|BlackBerry|IEMobile|Opera Mini/i.test(navigator.userAgent));
},
destroyed() {
window.removeEventListener('resize', this.handleResize)
},
created() {
//manage_mob_classes();
},

methods : {
isMobile() {
  return (/Android|webOS|iPhone|iPad|iPod|BlackBerry|IEMobile|Opera Mini/i.test(navigator.userAgent));
},

  handleResize() {
    if (!this.isMobile()) {
      this.isOpen = window.innerWidth > 800;
    }
  },

  manage_mob_classes() {
    if (/Android|webOS|iPhone|iPad|iPod|BlackBerry|IEMobile|Opera Mini/i.test(navigator.userAgent)) {
      $("nav").addClass("mob_nav");
      $("main").addClass("mob_main");
      $("#extraz").addClass("mob_extraz");
      $("#carbonads-container").addClass("mob_carbonads-container");
      this.isOpen  = false;
    } else {
      $("nav").removeClass("mob_nav") 
        $("main").removeClass("mob_main");
      $("#extraz").removeClass("mob_extraz");
      $("#carbonads-container").removeClass("mob_carbonads-container");
      this.isOpen  = true;
    }
  },

  toggleNav() {
    this.isOpen =! this.isOpen ;
    // alert("Toggle nav!");
    console.log("toggleNav() click: " + this.isOpen );
  }
}
})

$("#carbonads-container").append(ads);


$(function() {

    var darkmode = Cookies.get("darkmode");
    console.log("Document ready: " + darkmode);

    if ( darkmode  == "true" ) {
      $('#cssSelect').text("Light mode");
    } else {
      $('#cssSelect').text("Dark mode");
     }

    $('body').css('display','block');
    });

</script>

    
  </body> 
</html>

